<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
   
   <meta name="description" content="command line parsing">
    
    <meta name="author" content="John S. Urban" >
    <link rel="icon" href="./favicon.png">

    <title> M_CLI2 </title>

    <link href="./css/bootstrap.min.css" rel="stylesheet">
    <link href="./css/pygments.css" rel="stylesheet">
    <link href="./css/font-awesome.min.css" rel="stylesheet">
    <link href="./css/local.css" rel="stylesheet">
    
    <link  href="./tipuesearch/tipuesearch.css" rel="stylesheet">
    
    

    <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
    <!--[if lt IE 9]>
      <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
      <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    
    <script src="./js/jquery-2.1.3.min.js"></script>
    <script src="./js/svg-pan-zoom.min.js"></script>

  </head>

  <body>

    <!-- Fixed navbar -->
    <nav class="navbar navbar-inverse navbar-fixed-top">
      <div class="container">
        <div class="navbar-header">
          <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
            <span class="sr-only">Toggle navigation</span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
          </button>
          <a class="navbar-brand" href="./index.html">M_CLI2 </a>
        </div>
        <div id="navbar" class="navbar-collapse collapse">
          <ul class="nav navbar-nav">
        
            <li class="dropdown hidden-xs visible-sm visible-md hidden-lg">
              <a href="#" class="dropdown-toggle"
              data-toggle="dropdown" role="button"
              aria-haspopup="true"
     aria-expanded="false">Contents <span class="caret"></span></a>
        <ul class="dropdown-menu">
          
              
            <li><a href="./lists/files.html">Source Files</a></li>
        
        
        
            <li><a href="./lists/modules.html">Modules</a></li>
        
            
                                
            <li><a href="./lists/procedures.html">Procedures</a></li>
        
               
            <li><a href="./lists/types.html">Derived Types</a></li>
        
        
            <li><a href="./lists/programs.html">Programs</a></li>
        
            </ul>
            </li>


<li class="visible-xs hidden-sm visible-lg"><a href="./lists/files.html">Source Files</a></li>



<li class="visible-xs hidden-sm visible-lg"><a href="./lists/modules.html">Modules</a></li>



<li class="visible-xs hidden-sm visible-lg"><a href="./lists/procedures.html">Procedures</a></li>

                             
<li class="visible-xs hidden-sm visible-lg"><a href="./lists/types.html">Derived Types</a></li>


<li class="visible-xs hidden-sm visible-lg"><a href="./lists/programs.html">Programs</a></li>

          </ul>
        
        <form action="./search.html" class="navbar-form navbar-right" role="search">
        <div class="form-group">
          <input type="text" class="form-control" placeholder="Search" name="q" id="tipue_search_input" autocomplete="off" required>
        </div>
<!--
        <button type="submit" class="btn btn-default">Submit</button>
-->
        </form>
        
        </div><!--/.nav-collapse -->
      </div>
    </nav>

    <div class="container">
    
      <!-- Main component for a primary marketing message or call to action -->
      <div class="jumbotron">
        <p>command line parsing</p>
        	 
	<p> Find us on&hellip;</p>
        <p>
        	 
          <a class="btn btn-lg btn-primary" href="https://github.com/urbanjost/M_CLI2" role="button">GitHub</a>
			 
			 
			 
			 
	         
			 
        </p>
      </div>

      <div class="row" id='text'>
		  
        <div class="col-md-8">
		  
          <h1>M_CLI2</h1>
          <h1 id="m_cli2f90-and-associated-files">M_CLI2.f90 and associated files</h1>
<!--
![parse](docs/images/parse.png)
-->
<h2 id="name">NAME</h2>
<h3 id="m_cli2-parse-unix-like-command-line-arguments-from-fortran">M_CLI2 - parse Unix-like command line arguments from Fortran</h3>
<h2 id="description">DESCRIPTION</h2>
<p>M_CLI2(3f) is a Fortran module that will crack the command line when
   given a prototype string that looks very much like an invocation of
   the program. A call to get_args(3f) or one of its variants is then
   made for each parameter name to set the variables appropriately in
   the program.</p>
<h2 id="example-program">EXAMPLE PROGRAM</h2>
<p>This short program defines a command that can be called like</p>
<div class="codehilite"><pre><span></span><code>   ./show -x <span class="m">10</span> -y -20 -p <span class="m">10</span>,20,30 --title <span class="s1">&#39;plot of stuff&#39;</span> -L
   <span class="c1"># these parameters are defined automatically </span>
   ./show --usage 
   ./show --help
   ./show --version
   <span class="c1"># you must supply text for &quot;help&quot; and &quot;version&quot; if desired.</span>
</code></pre></div>

<div class="codehilite"><pre><span></span><code>   <span class="k">program </span><span class="n">show</span>
   <span class="k">use </span><span class="n">M_CLI2</span><span class="p">,</span> <span class="k">only</span> <span class="p">:</span> <span class="n">set_args</span><span class="p">,</span> <span class="n">lget</span><span class="p">,</span> <span class="n">rget</span><span class="p">,</span> <span class="n">sget</span><span class="p">,</span> <span class="n">igets</span>
   <span class="k">implicit none</span>
<span class="k">   </span><span class="kt">real</span>                          <span class="kd">::</span> <span class="nb">sum</span>
<span class="nb">   </span><span class="kt">integer</span><span class="p">,</span><span class="k">allocatable</span>           <span class="kd">::</span> <span class="n">p</span><span class="p">(:)</span>
   <span class="kt">character</span><span class="p">(</span><span class="nb">len</span><span class="o">=</span><span class="p">:),</span><span class="k">allocatable</span>  <span class="kd">::</span> <span class="n">title</span>
   <span class="kt">logical</span>                       <span class="kd">::</span> <span class="n">l</span><span class="p">,</span> <span class="n">lbig</span>
      <span class="c">! Define command and default values and parse supplied command line options</span>
      <span class="k">call </span><span class="n">set_args</span><span class="p">(</span><span class="s1">&#39;-x 1 -y 2.0 -z 3.5e0 -p 11,-22,33 --title &quot;my title&quot; -l F -L F&#39;</span><span class="p">)</span>
      <span class="c">! Get values using convenience functions</span>
      <span class="nb">sum</span><span class="o">=</span><span class="n">rget</span><span class="p">(</span><span class="s1">&#39;x&#39;</span><span class="p">)</span> <span class="o">+</span> <span class="n">rget</span><span class="p">(</span><span class="s1">&#39;y&#39;</span><span class="p">)</span> <span class="o">+</span> <span class="n">rget</span><span class="p">(</span><span class="s1">&#39;z&#39;</span><span class="p">)</span>
      <span class="n">title</span><span class="o">=</span><span class="n">sget</span><span class="p">(</span><span class="s1">&#39;title&#39;</span><span class="p">)</span>
      <span class="n">p</span><span class="o">=</span><span class="n">igets</span><span class="p">(</span><span class="s1">&#39;p&#39;</span><span class="p">)</span>
      <span class="n">l</span><span class="o">=</span><span class="n">lget</span><span class="p">(</span><span class="s1">&#39;l&#39;</span><span class="p">)</span>
      <span class="n">lbig</span><span class="o">=</span><span class="n">lget</span><span class="p">(</span><span class="s1">&#39;L&#39;</span><span class="p">)</span>
      <span class="k">write</span><span class="p">(</span><span class="o">*</span><span class="p">,</span><span class="o">*</span><span class="p">)</span><span class="nb">sum</span><span class="p">,</span><span class="n">l</span><span class="p">,</span><span class="n">lbig</span><span class="p">,</span><span class="n">p</span><span class="p">,</span><span class="n">title</span>
   <span class="k">end program </span><span class="n">show</span>
</code></pre></div>

<p>An arbitrary number of strings such as filenames may be passed in on
the end of commands, you can query whether an option was supplied, and
get_args(3f)-related routines can be used for refining options such as
requiring lists of a specified size. Passing in some character arrays
allows you to automatically have a &ndash;help and &ndash;version switch as well,
as explained below.</p>
<h2 id="demo-programs">DEMO PROGRAMS<img alt="demos" src="docs/images/demo.gif"></h2>
<p>These demo programs provide templates for the most common usage:</p>
<ul>
<li><a href="example/demo1.f90">demo1</a> using the convenience functions</li>
<li><a href="example/demo2.f90">demo2</a> putting everything including <strong>help</strong> and <strong>version</strong> information into a contained procedure.</li>
<li><a href="example/demo3.f90">demo3</a> example of <strong>basic</strong> use</li>
<li><a href="example/demo4.f90">demo4</a> <em>COMPLEX</em> type values</li>
<li><a href="example/demo5.f90">demo5</a> <em>CHARACTER</em> type values</li>
<li><a href="example/demo6.f90">demo6</a> a complicated example showing how to create a command with subcommands</li>
<li><a href="example/demo7.f90">demo7</a> controlling array delimiter characters</li>
<li><a href="example/demo8.f90">demo8</a> multiple keyword and variable pairs on get_args(3f) for limited cases</li>
<li><a href="example/demo9.f90">demo9</a> long and short names using  &ndash;LONGNAME:SHORTNAME</li>
<li><a href="example/demo10.f90">demo10</a> full usage and even equivalencing</li>
</ul>
<h2 id="download-and-build-with-make1">DOWNLOAD AND BUILD WITH make(1)<img alt="gmake" src="docs/images/gnu.gif"></h2>
<p>Compile the M_CLI2 module and build all the example programs.
   ```bash
       git clone https://github.com/urbanjost/M_CLI2.git
       cd M_CLI2/src
       # change Makefile if not using one of the listed compilers</p>
<div class="codehilite"><pre><span></span><code>   # <span class="k">for</span> <span class="nv">gfortran</span>
   <span class="nv">make</span> <span class="nv">clean</span>
   <span class="nv">make</span> <span class="nv">F90</span><span class="o">=</span><span class="nv">gfortran</span> <span class="nv">gfortran</span>

   # <span class="k">for</span> <span class="nv">ifort</span>
   <span class="nv">make</span> <span class="nv">clean</span>
   <span class="nv">make</span> <span class="nv">F90</span><span class="o">=</span><span class="nv">ifort</span> <span class="nv">ifort</span>

   # <span class="k">for</span> <span class="nv">nvfortran</span>
   <span class="nv">make</span> <span class="nv">clean</span>
   <span class="nv">make</span> <span class="nv">F90</span><span class="o">=</span><span class="nv">nvfortran</span> <span class="nv">nvfortran</span>

   # <span class="nv">display</span> <span class="nv">other</span> <span class="nv">options</span> <span class="ss">(</span><span class="nv">test</span>, <span class="nv">run</span>, <span class="nv">doxygen</span>, <span class="nv">ford</span>, ...<span class="ss">)</span>
   <span class="nv">make</span> <span class="nv">help</span>
</code></pre></div>

<p>```</p>
<h2 id="supports-fpm">SUPPORTS FPM <img alt="parse" src="docs/images/fpm_logo.gif"></h2>
<p>Alternatively, download the github repository and build it with
   fpm ( as described at <a href="https://github.com/fortran-lang/fpm">Fortran Package Manager</a> )</p>
<p><code>bash
        git clone https://github.com/urbanjost/M_CLI2.git
        cd M_CLI2
        fpm test   # build and test the module
    fpm install # install the module (in the default location)</code></p>
<p>or just list it as a dependency in your fpm.toml project file.</p>
<div class="codehilite"><pre><span></span><code>        <span class="k">[dependencies]</span>
        <span class="n">M_CLI2</span>        <span class="o">=</span> <span class="p">{</span> <span class="n">git</span> <span class="o">=</span> <span class="s">&quot;https://github.com/urbanjost/M_CLI2.git&quot;</span> <span class="p">}</span>
</code></pre></div>

<h2 id="functional-specification">FUNCTIONAL SPECIFICATION</h2>
<p><strong>This is how the interface works &ndash;</strong></p>
<ul>
<li>
<p>Pass in a string to set_args(3f) that looks almost like the command
  you would use to execute the program except with all keywords and
  default values specified.</p>
</li>
<li>
<p>you add calls to the get_args(3f) procedure or one of its variants (
  The alternatives allow you to use a simple function-based interface
  model. There are special routines for when you want to use fixed length.
  CHARACTER variables or fixed-size arrays instead of the allocatable
  variables best used with get_args(3f)).</p>
</li>
</ul>
<p>Now when you call the program all the values in the prototype should
  be updated using values from the command line and queried and ready
  to use in your program.</p>
<h2 id="response-files">RESPONSE FILES</h2>
<p><a href="response.md">Response files</a> are supported as described in the documentation for
<a href="https://urbanjost.github.io/M_CLI2/set_args.3m_cli2.html">set_args</a>.
They are a system-independent way to create short abbreviations for long
complex commands. This option is generally not needed by programs with
just a few options, but can be particularly useful for programs with
dozens of options where various values are frequently reused.</p>
<h2 id="documentation">DOCUMENTATION   <img alt="docs" src="docs/images/docs.gif"></h2>
<h3 id="man-pages-as-html">man-pages as HTML</h3>
<ul>
<li><a href="https://urbanjost.github.io/M_CLI2/man3.html">man-pages</a> &ndash; man-pages index of individual procedures</li>
<li><a href="https://urbanjost.github.io/M_CLI2/BOOK_M_CLI2.html">BOOK_M_CLI2</a> &ndash; All man-pages consolidated using JavaScript</li>
</ul>
<!--
   + [M_CLI2](https://urbanjost.github.io/M_CLI2/M_CLI2.3m_cli2.html) --
     An overview of the M_CLI2 module
   + [set_args](https://urbanjost.github.io/M_CLI2/set_args.3m_cli2.html) --
     parses the command line options
   + [get_args](https://urbanjost.github.io/M_CLI2/get_args.3m_cli2.html) --
     obtain parameter values for allocatable arrays and scalars.
     This also documents the functions iget,igets,rget,rgets,sget,sgets,lget,lgets, ... .

     **less frequently used**
   + [get_args_fixed_length](https://urbanjost.github.io/M_CLI2/get_args_fixed_length.3m_cli2.html) --
     obtain parameter values for fixed-length character variable
   + [get_args_fixed_size](https://urbanjost.github.io/M_CLI2/get_args_fixed_size.3m_cli2.html) --
     obtain parameter values for fixed-size arrays
   + [specified](https://urbanjost.github.io/M_CLI2/specified.3m_cli2.html) --
     query whether an option was used on the commandline
-->
<h3 id="real-man-pages">real man-pages <img alt="gmake" src="docs/images/manpages.gif"></h3>
<ul>
<li><a href="https://urbanjost.github.io/M_CLI2/manpages.zip">manpages.zip</a></li>
<li><a href="https://urbanjost.github.io/M_CLI2/manpages.tgz">manpages.tgz</a></li>
</ul>
<h3 id="developer-documentation">developer documentation</h3>
<ul>
<li><a href="https://urbanjost.github.io/M_CLI2/doxygen_out/html/index.html">doxygen(1) output</a>.</li>
<li><a href="https://urbanjost.github.io/M_CLI2/fpm-ford/index.html">ford(1) output</a>.</li>
</ul>
<h3 id="logs">logs</h3>
<ul>
<li><a href="docs/CHANGELOG.md">CHANGELOG</a></li>
<li><a href="docs/STATUS.md">STATUS</a> of most recent CI/CD runs</li>
</ul>
<h2 id="commit-tests">COMMIT TESTS</h2>
<p>commit <code>598e44164eee383b8a0775aa75b7d1bb100481c3</code> was tested on 2020-11-22 with
 + GNU Fortran (GCC) 8.3.1 20191121 (Red Hat 8.3.1-5)
 + ifort (IFORT) 19.1.3.304 20200925
 + nvfortran 20.7-0 LLVM 64-bit target on x86-64 Linux</p>
<p>commit <code>8fe841d8c0c1867f88847e24009a76a98484b31a</code> was tested on 2021-09-29 with
 + GNU Fortran (Ubuntu 10.3.0-1ubuntu1~20.04) 10.3.0
 + ifort (IFORT) 2021.3.0 20210609
 + nvfortran 21.5-0 LLVM 64-bit target on x86-64 Linux -tp nehalem </p>
<hr>
<h2 id="last-updated-wed-sep-29-173452-2021-0400">Last updated:   Wed Sep 29 17:34:52 2021 -0400</h2>
        </div>
		  
        <div class="col-md-4">
	  <div class="well">
          <h2>Developer Info</h2>
          <h4>John S. Urban</h4>
          
          
			   
            <div class="text-center"><div class="btn-group" role="group">
              
              
              
              <a class="btn btn-lg btn-primary" href="https://github.com/urbanjost/M_CLI2"><i class="fa fa-github fa-lg"></i></a>
				  
				  
              
              
              
              
            </div></div>
            
       </div>
       </div>
       
      </div>
      
      
      
      
		
      <div class="row">
        <div class="col-xs-6 col-sm-3">
              <h3>Source Files</h3>
              <ul>
                
                  
                    <li><a href='./sourcefile/demo1.f90.html'>demo1.f90</a></li>
                  
                
                  
                    <li><a href='./sourcefile/demo10.f90.html'>demo10.f90</a></li>
                  
                
                  
                    <li><a href='./sourcefile/demo11.f90.html'>demo11.f90</a></li>
                  
                
                  
                    <li><a href='./sourcefile/demo1b.f90.html'>demo1B.f90</a></li>
                  
                
                  
                    <li><a href='./sourcefile/demo2.f90.html'>demo2.f90</a></li>
                  
                
                  
                    <li><a href='./sourcefile/demo3.f90.html'>demo3.f90</a></li>
                  
                
                  
                    <li><a href='./sourcefile/demo4.f90.html'>demo4.f90</a></li>
                  
                
                  
                    <li><a href='./sourcefile/demo5.f90.html'>demo5.f90</a></li>
                  
                
                  
                    <li><a href='./sourcefile/demo6.f90.html'>demo6.f90</a></li>
                  
                
                  
                    <li><a href='./sourcefile/demo7.f90.html'>demo7.f90</a></li>
                  
                
                  
                    <li><a href="./lists/files.html"><em>All source files&hellip;</em></a></li>
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
              </ul>
          </div>
          
		  <div class="col-xs-6 col-sm-3">
              <h3>Modules</h3>
              <ul>
                
                  
                    <li><a href='./module/m_cli2.html'>M_CLI2</a></li>
                  
                
              </ul>
          </div>
          
          
		  <div class="col-xs-6 col-sm-3">
              <h3>Procedures</h3>
              <ul>
                
                  
                    <li><a href='./proc/cget.html'>cget</a></li>
                  
                
                  
                    <li><a href='./interface/cgets.html'>cgets</a></li>
                  
                
                  
                    <li><a href='./proc/dget.html'>dget</a></li>
                  
                
                  
                    <li><a href='./interface/dgets.html'>dgets</a></li>
                  
                
                  
                    <li><a href='./interface/get_args.html'>get_args</a></li>
                  
                
                  
                    <li><a href='./interface/get_args_fixed_length.html'>get_args_fixed_length</a></li>
                  
                
                  
                    <li><a href='./interface/get_args_fixed_size.html'>get_args_fixed_size</a></li>
                  
                
                  
                    <li><a href='./proc/get_subcommand.html'>get_subcommand</a></li>
                  
                
                  
                    <li><a href='./proc/iget.html'>iget</a></li>
                  
                
                  
                    <li><a href='./interface/igets.html'>igets</a></li>
                  
                
                  
                    <li><a href="./lists/procedures.html"><em>All procedures&hellip;</em></a></li>
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
                  
                
              </ul>
          </div>
          
          
		  <div class="col-xs-6 col-sm-3">
              <h3>Derived Types</h3>
              <ul>
                
                  
                    <li><a href='./type/point.html'>point</a></li>
                  
                
              </ul>
          </div>
          
      </div>

    <hr>    
    </div> <!-- /container -->
    <footer>
      <div class="container">
      <div class="row">
        <div class="col-xs-6 col-md-4"><p>&copy; 2022 
                                          </p></div>
        <div class="col-xs-6 col-md-4 col-md-push-4">
          <p class="text-right">
            Documentation generated by 
            <a href="https://github.com/cmacmackin/ford">FORD</a>
             on 2022-06-08 21:13  
          </p>
        </div>
        <div class="col-xs-12 col-md-4 col-md-pull-4"><p class="text-center"> M_CLI2 was developed by John S. Urban</p></div>
      </div>
      <br>
      </div> <!-- /container -->    
    </footer>

    <!-- Bootstrap core JavaScript
    ================================================== -->
    <!-- Placed at the end of the document so the pages load faster -->
<!--
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
-->
    <script src="./js/bootstrap.min.js"></script>
    <!-- IE10 viewport hack for Surface/desktop Windows 8 bug -->
    <script src="./js/ie10-viewport-bug-workaround.js"></script>

    <!-- MathJax JavaScript
    ================================================== -->
    <!-- Placed at the end of the document so the pages load faster -->
    <script type="text/x-mathjax-config">
      MathJax.Hub.Config({
        TeX: { extensions: ['AMSmath.js','AMSsymbols.js','noErrors.js','noUndefined.js'], equationNumbers: { autoNumber: 'AMS' } },
        jax: ['input/TeX','input/MathML','output/HTML-CSS'],
        extensions: ['tex2jax.js','mml2jax.js','MathMenu.js','MathZoom.js']
      });
    </script>
    
    <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
    
    
    <script src="./tipuesearch/tipuesearch_content.js"></script>
    <script src="./tipuesearch/tipuesearch_set.js"></script>
    <script src="./tipuesearch/tipuesearch.js"></script>
    
    
  </body>
</html>